BLESS - BLitz EventS System - Take control of Windows events!
Written by Chad Dylan Long
Copyright 2004 by Minty Software, LLC
www.mintysoftware.com

--------------
What is BLESS?
--------------

BLESS stands for "BLitz EventS System".  It is a small DLL made to augment the event-handling power of BlitzPlus and Blitz3D, hopefully alleviating some of their shortcomings.

-----------------------
Why would I want BLESS?
-----------------------

BlitzPlus users, have you ever wished BlitzPlus had a certain feature, and been frustrated to find that you couldn't code it yourself because of the shortcomings of the language?  Blitz3D users, have you ever wanted some of the event-handling power of BlitzPlus?

BLESS increases the number of Windows events your program can monitor and react to.  BlitzPlus gives you access to 21 (or so) events.  Blitz3D mostly just gives you access to input-related events.  But, with BLESS, you can monitor and react to pretty much any Windows event that occurs for any window -- not just your own Blitz window.

Also, BLESS is built to be very open-ended.  With a little knowledge of the Windows API and some documentation from MSDN, it can be a very powerful tool.  It was written to be as unintrusive as possible, doing only what Blitz CAN'T do, thereby letting you, the Blitz programmer, implement whatever you like, however you like.

-------------------------
What can I do with BLESS?
-------------------------

Here are some of the things BLESS allows you to do, as shown in the example programs:
1) Create your own custom Windows gadgets by catching WM_PAINT and WM_DRAWITEM messages 
2) Catch mouse events from any gadget
3) Monitor keypresses in another program, like notepad
4) Minimize your app to the system tray
5) Monitor system tray events, like clicks and mousemoves
6) Know when other windows are closed
7) Know when CUT, COPY, and PASTE are used
8) Know when a treeview node is expanded or contracted
9) Know when any item in any gadget (treeview, listbox, etc) is changed... with the mouse OR keyboard
10) Drag-and-Drop files into your window

But since there are so many different Windows messages, notifications, and events, there are many more possibilities with BLESS.

--------------------
How does BLESS work?
--------------------

You tell BLESS an event and gadgets/window you're interested in, and when BLESS notices the particular event happening to the particular gadget or window, it lets you know by sending a BLESS event to your Blitz program.  What is a BLESS event?  For BlitzPlus, the BLESS event is disguised as a special character code from the unused portion of the UTF-16 (unicode) range.  For Blitz3D, it is disguised as a scancode for a non-existent keyboard key.  Either way, for you to detect the event, it's as simple as using KeyHit (Blitz3D) or event $103 (Keystroke in BlitzPlus).

-------------------
How do I use BLESS?
-------------------

See "Bless Docs.txt" for more info.  To quickly get up and running, it's as simple as this:

1) Put bless.bb and bless.dll in your development folder
2) Put bless.decls in your userlib folder
3) In your sourcecode, use:
	Include "bless.bb"
4) If you're using Blitz3D, use this line:
	Bless_UseAlternateMethod(True) ; Alternate BLESS event notification method
5) Then let BLESS know which event and window you want to monitor with Bless_RegisterEvent()
6) In your main loop or event loop, check BLESS events with KeyHit or event $103
7) Use EventData() to get any extended event information, if necessary
8) Before terminating your program, call:
	Bless_UnregisterEvent(0)

That's it.  Also, check out the examples' source code.

--------------------------------
Are there known issues in BLESS?
--------------------------------

Yes, BLESS is currently classified as beta.  Here are some issues:

* Some problems may occur when running more than one program that uses BLESS (at the same time)
* In the Notepad Demo, sometimes Blitz3D doesn't process the WM_DESTROY message after rapidly pressing a bunch of characters and quickly closing Notepad
* If Bless_UnregisterEvent(0) isn't called before program termination, Windows may not completely unload the DLL for a few minutes, during which time BLESS events may not work completely.
* Since Bless_EventData only returns information for the last event that occurred of a certain BLESS event ID, any previous event data not queried will be lost.  So, if events occur very rapidly, (like WM_MOUSEMOVE while rapidly moving the mouse), not all mouse event coordinates may be able to be retrieved.

-------------------------------------
Is there unknown territory for BLESS?
-------------------------------------

Yes, I'm interested in knowing how the following work:

1) Detecting some events (like WM_COMMAND and WM_NOTIFY) on Win95/98/ME systems
2) BLESS on Unicode-enabled systems (using the default BLESS event method)
3) BLESS on slow systems
4) BLESS on weirdo keyboards and other input devices (using the alternate BLESS event method)
